Summary

Let agents address Project v2 fields, options, and item values by name (read +write) instead of pre-resolved IDs. Resolution happens in the wrapper; the mutation stays ID-typed.

Why

Today an agent that wants to update a project field has to assemble several opaque IDs (project, item, field, single-select option) before it can write. The MCP update_project_item tool is only partly there, it accepts owner login, project number, and issue number, but the write still demands the field ID and item ID and does no option-name resolution.

update_project_item demands field ID + item ID and does no option-name resolution. Reads are ID-bound too: list_project_items returns only Title, so reading a field value needs a list_project_fields. This forces a list-and-filter dance, burns context, and invites mis-bound IDs.

The important part: this is a surfacing gap, not a platform gap. The GraphQL API already resolves names projectV2.field(name:), ProjectV2SingleSelectField.options(names:), ProjectV2Item.fieldValueByName(name:), plus top-level lookups by login / owner+name / project number. A single nested read can fetch every ID the write needs. The agent surface simply doesn't pass those resolvers through.

Closes #3430

What changed

• Write: update_project_item accepts a field via updated_field.name, resolves the single-select option by name, and resolves the item by item_owner + item_repo + issue_number when item_id is omitted. {id}/{name} mutually exclusive.
• Read: new optional field_names on get_project_item / list_project_items no list_project_fields preflight.
• Errors: name failures return typed, self-correctable JSON (field_not_found, field_ambiguous, option_not_found, item_not_in_project, …) with candidates. Backward compatible, existing ID paths unchanged; new inputs additive/optional.

Follow-up

• Pagination: item resolution reads projectItems(first: 50), bound and paginate Project item read payloads so an agent can pull field values for a large board without overflowing its buffer or burning context. #3332.

MCP impact

• No tool or API changes
• Tool schema or behavior changed
• New tool added

Prompts tested (tool changes only)

Security / limits

• No security or limits impact
• Auth / permissions considered
• Data exposure, filtering, or token/size limits considered

Schema token delta, measured with o200k_base:

How this was measured

Used mcpcurl schema to dump the tools/list payload (name + description +inputSchema) on main vs. this branch, tokenized both with tiktoken (o200k_base encoding), and diffed.

Tool renaming

• I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
  • I have added the new tool aliases in deprecated_tool_aliases.go
• I am not renaming tools as part of this PR

Note: if you're renaming tools, you must add the tool aliases. For more information on how to do so, please refer to the official docs.

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Docs

• Not needed
• Updated (README / docs / examples)